<!DOCTYPE html>
<html>
<head>
	<title>Internationalization</title>
	<meta charset="utf-8">
	<link href="./manual.css" rel="stylesheet" type="text/css">
</head>
<body>
	<div id="container">
		<header class="logo-header">
			<img class="header-logo" alt="Logo" src="puppylogo96.png">
			<h1>HOWTO internationalize applications</h1>
		</header>
		<p>Page updated May 12, 2013</p>
		<p>
			Internationalization of applications and scripts in Puppy Linux has become extremely easy, with MoManager, a GUI application.
		</p>
		<section>
			<h2>Scripts internationalized with 'gettext'</h2>
			<p>
				There are a lot of scripts in Puppy that use 'gettext' for translating. Here are some in /usr/sbin:
				<ul class="code">
					<li>connectwizard</li>
					<li>hostname-set</li>
					<li>keymap-set</li>
					<li>mousecheck</li>
					<li>quicksetup</li>
					<li>shutdownconfig</li>
				</ul>
				Inside each script you will find a line like this:
				<code>export TEXTDOMAIN=myapp</code>
				MoManager finds all scripts with this entry, which confirms that it uses 'gettext', and offers a GUI interface for translating each script. You do not have to learn the commandline tools for translating, the GUI interface makes it easy.
			</p>
			<p>
				Basically, MoManager will create a .pot file for the application, in the above example that will be 'myapp.pot'. Note that multiple scripts can have the same domainname 'myapp' and just the one 'myapp.pot' will be created. So, if your application has several scripts, you don't have to have a .pot for each (but you can if you want), just have the one .pot -- this is more efficient if there are common text strings to be translated in the scripts, and is simpler just to have the one .pot file.
			</p>
			<p>
				One technical detail: please place the "export ..." at column one, and do not place quotes around "myapp", the line in the script should look just like I have shown:
				<code>export TEXTDOMAIN=myapp</code>
				.pot files are "translation files", which you then have to insert the translations for a particular language. When that is done, it becomes a .po file, and it is then compiled to a binary form and becomes a .mo file. The compiled .mo files are kept at /usr/share/locale. MoManager handles these conversions for you.
			</p>
			<section>
				<h3>Pre-existing .pot files</h3>
				<p>
					MoManager will create a .pot file from the script, however the commandline-tool (xgettext) to extract the text strings from the script and create the .pot file does not always work properly. An example is /usr/sbin/xxx -- in this case, we have a pre-existing .pot file, /usr/share/doc/nls/xxx/xxx.pot.
				</p>
				<p>
					MoManager will automatically use any pre-existing .pot file that it finds in /usr/share/doc/nls, rather than use xgettext to extract the strings from the script(s).
				</p>
			</section>
		</section>
		<section>
			<h2>MoManager translation manager</h2>
			<p>
				MoManager is a GUI application written by me (Barry Kauler) that makes it very easy for anyone to create non-English translations for applications in Puppy. You must have a Puppy built from a Woof version later than February 14, 2012, however if you want to use MoManager to create a "langpack" for a particular language it is recommended to use the very latest Puppy built from latest Woof -- see my blog (<a href="http://bkhome.org/blog2/">http://bkhome.org/blog2</a>) for announcements of Puppy builds.
			</p>
			<p>
				MoManager is for creating and updating translation files for scripts, XML files, menu files, any other data text files, and binary executables.
			</p>
			<p>
				Scripts are applications that are text files, usually written in Bash or Ash (or Perl, Python, Tcl, etc.). Note, if you are unfamiliar with 'scripts', don't worry, they are just applications.
			</p>
			<p>
				To use MoManager, the best thing to do is just go ahead and use it. You will find it in the 'Utility' menu. Once started, you will see two columns of drop-down lists, one list is of files that already have a translation file for your language (on left side), the other list is for files that do not yet have a translation file. if you select a file from the formerlist, you may update the translation, and in the latter case you may create a new translation file.
			</p>
			<p>
				<div>Here is a snapshot of the main window, Puppy running with de_DE locale:</div>
				<img style=" width: 862px; height: 664px;" alt="MoManager" src="http://puppylinux.com/development/MoManager.png">
			</p>
			<section>
				<h3>Scripts</h3>
				<p>
					In the case of updating an existing translation file, MoManager automatically synchronises with the latest script, and will identify any changed strings -- if you see the text "fuzzy" anywhere in the translation file, it is likely that the original English text has changed and you will need to update the translation.
				</p>
				<p>
					A translation file for a script means that when the application runs, it will output all text in your language. By creating translation files for all the scripts, you can help to create a Puppy that runs nicely in your language.
				</p>
				<p>
					Although it is probably possible to figure out how to edit a translation file, known as a 'po' file in it's editable form, or 'mo' file in it's compiled form, it is helpful to readup a bit on the topic. I suggest:
					<ul>
						<li><a href="http://translate.sourceforge.net/wiki/guide/project/howto">http://translate.sourceforge.net/wiki/guide/project/howto</a></li>
						<li><a href="http://www.gnu.org/software/gettext/manual/html_node/gettext_9.html#PO-Files">http://www.gnu.org/software/gettext/manual/html_node/gettext_9.html#PO-Files</a></li>
					</ul>
					...note though, reading all of that can be confusing! It is possible to use MoManager without understanding all of those details. MoManager uses a normal text editor to edit .po files rather than a specialized po-editor (such as poedit) and this is quite easy to do, you just need a very basic understanding of the format of .po files.
				</p>
			</section>
			<section>
				<h3>poedit</h3>
				<p>
					This is a special text editor for .po files. Although MoManager uses the default text editor (usually Geany in most puppies), if poedit is installed then MoManager can use it -- you will see a checkbox in the main window of MoManager to choose poedit.
				</p>
				<p>
					To install poedit, look in the Puppy Package Manager. Most builds of Puppy will have it available.
				</p>
			</section>
			<section>
				<h3>Langpack</h3>
				<p>
					You will also see in the MoManager window, a button to generate a "langpack" PET package. if you would like to translate Puppy for a particular language, this button is very nice. It will gather up all the translations for your language and put them into a PET package, which you can then send to me, and I can place it along with the others at ibiblio.org. See the existing "langpacks" at ibiblio.org, named "langpack_*.pet", for example "langpack_de-20120729.pet":
				</p>
				<p>
					<a href="http://distro.ibibilio.org/quirky/pet_packages-noarch/">http://distro.ibibilio.org/quirky/pet_packages-noarch/</a>
				</p>
				<p>
					Note that the langpack is accumulative. Say for example that you install "langpack_de-20120729.pet" (German). You can then create some more translations, or update existing ones, then click the "Create langpack PET" button, and a new updated PET will be created. Please let me know if this mechanism leaves anything out!
				</p>
				<p>
					There are already maintainers for some languages, for example Puppy Forum member L18L maintains the German translation. So, if you want to contribute to the German translations please do it through L18L. At the time of writing, these are the translators:
				<table>
				  <tbody>
					<tr>
				  <td>da</td>
				  <td>Danish</td>
				  <td>maans</td>
				</tr>
				<tr>
					  <td>de
					  </td>
					  <td>German</td>
				<td>L18L
					  </td>
					</tr>
					<tr>
				  <td>el</td>
				  <td>Greek</td>
				  <td>kounelii</td>
				</tr>
				<tr>
					  <td>es
					  </td>
					  <td>Spanish</td>
				<td>vicmz
					  </td>
					</tr>
					<tr>
					  <td>fr
					  </td>
					  <td>French</td>
				<td>esmourguit
					  </td>
					</tr>
					<tr>
				  <td>it</td>
				  <td>Italian</td>
				  <td>vicmz (temporary)</td>
				</tr>
				<tr>
				  <td>nl</td>
				  <td>Dutch</td>
				  <td>Bert</td>
				</tr>
				<tr>
				  <td>pl</td>
				  <td>Polish</td>
				  <td>robwoj44</td>
				</tr>
				<tr>
				  <td>pt</td>
				  <td>Portuguese</td>
				  <td>vicmz</td>
				</tr>
				<tr>
					  <td>ru
					  </td>
					  <td>Russian</td>
				<td>rodin.s
					  </td>
					</tr>
				  </tbody>
				</table>
			</section>
			<section>
				<h3>Further information</h3>
				<p>
					If you want to learn more about MoManager, go to my blog <a href="http://bkhome.org/blog">http://bkhome.org/blog</a> and <a href="http://bkhome.org/blog2/">http://bkhome.org/blog2</a> (my new blog), and type "MoManager" into the search box.
				</p>
				<p>
					To interact with others working on translating Puppy, including asking questions about anything that puzzles you, please go to the Puppy Forum here: <a href="http://www.murga-linux.com/puppy/index.php?f=16">http://www.murga-linux.com/puppy/index.php?f=16</a>
				</p>
			</section>
		</section>
		<footer>
			Regards,<br>
			Barry Kauler
			<div class="legal">(c) This page is Copyright Barry Kauler 2012, 2013, all rights reserved.</div>
		</footer>
	</div>
</body>
</html>